home *** CD-ROM | disk | FTP | other *** search
/ NeXT Enterprise Objects Framework 1.1 / NeXT Enterprise Objects Framework 1.1.iso / NextDeveloper / Headers / foundation / NSDate.h < prev    next >
Encoding:
Text File  |  1994-05-14  |  10.4 KB  |  276 lines
  1. /*    NSDate.h
  2.     Primitives for manipulating time
  3.       Copyright 1993, 1994, NeXT, Inc.
  4.     NeXT, July 1993
  5.     
  6.     Portions of the NSDate implementation are derived from
  7.     public domain software described in
  8.      ``Calendrical Calculations'' by Nachum Dershowitz and
  9.      Edward M. Reingold, Software---Practice & Experience,
  10.     vol. 20, no. 9 (September, 1990), pp. 899--928 and from
  11.     ``Calendrical Calculations, II: Three Historical Calendars''
  12.     by Edward M. Reingold,  Nachum Dershowitz, and Stewart M. Clamen,
  13.     Software---Practice & Experience, vol. 23, to appear.
  14.  
  15. */
  16.  
  17. #import <foundation/NSString.h>
  18. #import <foundation/NSArray.h>
  19. #import <foundation/NSDictionary.h>
  20. #import <sys/time.h>
  21.  
  22. /* This module implements the 'date and time' concept.  Features:
  23.     - it is easy to compare dates and deal with time intervals;
  24.     - fast (can use the native representation);
  25.     - accuracy (other date representations can be added to the framework);
  26.     - can support user-oriented representations (Gregorian, etc ...);
  27.     - dates are immutable;
  28.     - an absolute reference date to ease conversion to other representations; 
  29. Our absolute reference date is the first instant of Jan 1st, 2001.
  30. All representations must be able to convert to/from that absolute reference.
  31. We ignore leap second accounting (e.g. pretend that they don't happen).
  32. Our reference date corresponds to 978307200 seconds after the UNIX base (e.g.
  33. 1/1/1970 to 1/1/2001 is (31*365 + 8 (leaps: 1972, .., 2000))*24*60*60)
  34.  
  35. Another interesting number is the number of seconds to the Julian Epoch, 
  36. JD 0.0 = 12 noon on 1 Jan 4713 B.C.E., which is -51909.5L*24*60*60
  37.  
  38. */
  39.  
  40. typedef double NSTimeInterval;
  41.     /* always in seconds; 
  42.     yields sub-millisecond precision over a range of 10000 years */
  43.  
  44. /***************    Date basics        ***************/
  45.  
  46. @interface NSDate:NSObject <NSCopying>
  47.  
  48. - (NSTimeInterval)timeIntervalSinceReferenceDate;
  49.     /* >0 if self is in the 3rd millenium */
  50.  
  51. @end
  52.  
  53. @interface NSDate (NSExtendedDate)
  54.  
  55. - (NSTimeInterval)timeIntervalSinceDate:(NSDate *)anotherDate;
  56.     /* >0 if self is ahead of anotherDate;
  57.     Conversion between two dates using the same representation should be exact */
  58.  
  59. - (NSTimeInterval)timeIntervalSinceNow;
  60.     /* >0 if self is in the future */
  61.  
  62. - (NSDate *)addTimeInterval:(NSTimeInterval)seconds;
  63.     /* Returns an auto-released date; 
  64.     may return a date from a different representation */
  65.  
  66. - (NSDate *)earlierDate:(NSDate *)anotherDate;
  67. - (NSDate *)laterDate:(NSDate *)anotherDate;
  68. - (NSComparisonResult)compare:(NSDate *)other;
  69.  
  70. - (BOOL)isEqual:other;
  71.     /* are the two dates within less than a second of each other? */
  72.  
  73. + (NSTimeInterval)timeIntervalSinceReferenceDate;
  74.     /* returns the timeInterval of now to the reference date (<0 until 2001) */
  75.     
  76. @end
  77.  
  78. /***************    Creation of basic dates        ***************/
  79.  
  80. @interface NSDate (NSDateCreation)
  81.  
  82. + allocWithZone:(NSZone *)zone;
  83.     /* Create an uninitialized instance of a concrete date;
  84.     When called with NSDate, substitutes a concrete class that guarantees a wide dynamic range, but as accurate as possible for dates close to boot time for use in timers;
  85.     +alloc can also be used to that effect */
  86.  
  87. + (NSDate *)date;
  88.     /* now! */
  89.     
  90. + (NSDate *)dateWithTimeIntervalSinceNow:(NSTimeInterval)secs;
  91.     /* Creates a new autoreleased date before or after now */
  92.     
  93. + (NSDate *)dateWithTimeIntervalSinceReferenceDate:(NSTimeInterval)secs;
  94.     /* Creates a new autoreleased date before or after the absolute reference date */
  95.     
  96. + (NSDate *)distantFuture;
  97.     /* a date far far into the future */
  98.     
  99. + (NSDate *)distantPast;
  100.     /* a date far far in the past */
  101.     
  102. - initWithTimeIntervalSinceReferenceDate:(NSTimeInterval)secsToBeAdded;
  103.     /* Designated initializer: MUST BE IMPLEMENTED BY CONCRETE CLASSES;
  104.     Creates a new date before or after the absolute reference date */
  105.  
  106. - init;
  107.     /* Designated initializer: MUST BE IMPLEMENTED BY CONCRETE CLASSES;
  108.     returns the date for now */
  109.  
  110. - (NSDate *)initWithTimeInterval:(NSTimeInterval)secsToBeAdded sinceDate:(NSDate *)anotherDate;
  111.     /* initializes a date given an offset from anotherDate;
  112.     Conversion between two dates using the same representation should be exact;
  113.     offset may be <0 (date is before anotherDate); */
  114.  
  115. - (NSDate *)initWithTimeIntervalSinceNow:(NSTimeInterval)secsToBeAddedToNow;
  116.     /* initializes a date given an offset from now;
  117.     offset may be <0 (date is before now); */
  118.  
  119. @end
  120.  
  121. /************ Time Zone Abstract Class *********************************/
  122.  
  123. /* An abstract TimeZone class.  TimeZones provide "locality" to universal dates.  Since many areas provide Daylight Savings Time in one form or another, we consider a NSTimeZone to represent the geo-political area, and a NSTimeZoneDetail as a specialization that contains the details of abbreviation and offset.
  124.    Private concrete classes are provided that supply
  125.       - unnamed offset style timezones, e.g. +0900
  126.       - unchanging named timezones "GMT" +0000
  127.       - varying timezones, e.g. PST/PDT, derived from underlying
  128.       system resources
  129.    The initialization method will substitute a private concrete instance.
  130.  */
  131.  
  132. @class NSTimeZoneDetail;
  133.  
  134. @interface NSTimeZone: NSObject <NSCopying>
  135.  
  136. // The default time zone is established via TZFILE environment variable
  137. // which should name a path for tzfile(5) information 
  138. // (/etc/zoneinfo/localtime is the default if TZFILE is not set)
  139. + (void)setDefaultTimeZone:(NSTimeZone *)aTimeZone;
  140. + (NSTimeZoneDetail *)defaultTimeZone;
  141.  
  142. // provides a defaultTimeZone look-alike except that when decoding
  143. // it replaces itself with the current defaultTimeZone
  144. // this is useful for NSCalendarDates that have a particular
  145. // format but wish to always use the current (local) timezone.
  146. + (NSTimeZone *)localTimeZone;
  147.  
  148. + (NSDictionary *)abbreviationDictionary;
  149.    // maps abbreviation to regionName (which is currently a file name)
  150.    // e.g. { PST = US/Pacific; PDT = US/Pacific; MDT = US/Mountain; ...}
  151.    // keys may be used to obtain timeZones via timeZoneWithName
  152.    // values may also be used to obtain timezones via timeZoneWithRegionName
  153.  
  154. + (NSArray *)timeZoneArray;
  155.    // supplies all regionNames grouped as subarrays per geographical region
  156.    // e.g. ( ... ( US/Pacific, US/Pacific-New, Canada/Pacific), ...)
  157.  
  158. + (NSTimeZone *)timeZoneWithName:(NSString *)aTimeZoneName;
  159.    // provide timezone with this timeZoneName
  160.    // currently, timeZoneName names a file in tzfile(5) format
  161.  
  162. + (NSTimeZone *)timeZoneWithAbbreviation:(NSString *)abbreviation;
  163.    // provide timezone with this abbreviation (if in abbreviationDictionary)
  164.    
  165. + (NSTimeZone *)timeZoneForSecondsFromGMT:(int)seconds;
  166.    // yield an unnamed timezone for this offset
  167.  
  168. - (NSString *)timeZoneName;
  169.  
  170. - (NSArray *)timeZoneDetailArray;
  171. - (NSTimeZoneDetail *)timeZoneDetailForDate:(NSDate *)date;
  172.  
  173. @end
  174.  
  175. @interface NSTimeZoneDetail : NSTimeZone
  176. - (int)timeZoneSecondsFromGMT;
  177. - (NSString *)timeZoneAbbreviation;
  178. - (BOOL) isDaylightSavingTimeZone;
  179. @end
  180.  
  181. /***************    Calendar Utilities        ***************/
  182.  
  183.  
  184.     /* Calendar formatting
  185.         %% encode a '%' character
  186.     %a abbreviated weekday name
  187.     %A full weekday name
  188.     %b abbreviated month name
  189.     %B full month name
  190.     %c shorthand for %X %x, the locale format for date and time
  191.     %d day of the month as a decimal number (01-31)
  192.     %H hour based on a 24-hour clock as a decimal number (00-23)
  193.     %I hour based on a 12-hour clock as a decimal number (01-12)
  194.     %j day of the year as a decimal number (001-366)
  195.     %m month as a decimal number (01-12)
  196.     %M minute as a decimal number (00-59)
  197.     %p AM/PM designation associated with a 12-hour clock
  198.     %S second as a decimal number (00-61)
  199.     %w weekday as a decimal number (0-6), where Sunday is 0
  200.     %x date using the date representation for the locale
  201.     %X time using the time representation for the locale
  202.     %y year without century (00-99)
  203.     %Y year with century (e.g. 1990)
  204.     %Z time zone name
  205.       and additionally
  206.           %z timezone offset in hours & minutes from GMT (HHMM)
  207.     
  208.       as a convenience, a '.' before the format characters dHIjmMSy will
  209.       suppress the leading 0, a ' ' (space) will preserve the normal field
  210.       width and supply spaces instead of 0's.  XXX not yet
  211.    */
  212.    
  213.  
  214. @interface NSCalendarDate : NSDate {
  215.     NSTimeInterval _timeIntervalSinceReferenceDate;
  216.     NSTimeZoneDetail *_timeZone;
  217.     NSString *_formatString;
  218. }
  219.  
  220. + (NSCalendarDate *)dateWithYear:(int)year month:(unsigned)month day:(unsigned)day hour:(unsigned)hour minute:(unsigned)minute second:(unsigned)second timeZone:(NSTimeZone *)aTimeZone;
  221.  
  222. + (NSCalendarDate *)dateWithString:(NSString *)description calendarFormat:(NSString *)format;
  223.  
  224. - initWithYear:(int)year month:(unsigned)month day:(unsigned)day hour:(unsigned)hour minute:(unsigned)minute second:(unsigned)second timeZone:(NSTimeZone *)aTimeZone;
  225.     /* e.g. [[NSDate alloc] initWithYear:1789 month:7 day:14 hour:12 minute:0 second:0 timeZone:[NSTimeZone timeZoneForKey@"MST"]]; 
  226.     raises if no timezone supplied */
  227.     
  228. - initWithString:(NSString *)description;
  229.      /* inverts 1994-01-14 15:25:02 +0900 */
  230.  
  231.     
  232. - initWithString:(NSString *)description calendarFormat:(NSString *)format;
  233.  
  234. - (NSTimeZoneDetail *) timeZoneDetail;
  235. - (void)setTimeZone:(NSTimeZone *)aTimeZone;    // picks the correct detail
  236.  
  237. - (NSString *)calendarFormat;
  238. - (void)setCalendarFormat:(NSString *)format;
  239.     /* default: %Y-%m-%d %H:%M:%S %z for an international style header */
  240.  
  241. - (int)yearOfCommonEra;    /* 1 C.E. (AD) is the base */
  242. - (int)monthOfYear;    /* 1 - 12 */
  243. - (int)dayOfMonth;    /* 1 - 31 */
  244. - (int)dayOfWeek;    /* 0 - 6 */
  245. - (int)dayOfYear;    /* 1 - 366 */
  246. - (int)hourOfDay;    /* 0 - 23 */
  247. - (int)minuteOfHour;    /* 0 - 59 */
  248. - (int)secondOfMinute;    /* 0 - 59 */
  249.  
  250. - (NSCalendarDate *)addYear:(int)year month:(int)month day:(int)day hour:(int)hour minute:(int)minute second:(int)second;
  251.     /* All offsets may be negative; autoreleased result.
  252.        Will attempt to retain class
  253.        Adding 1 day across a timezone change will keep the same hour/minute/second offset (e.g. 2:30pm will stay 2:30pm)  */
  254.  
  255. - (NSString *)description;
  256.     /* uses calendarFormat and timeZone */
  257.  
  258. - (NSString *)descriptionWithCalendarFormat:(NSString *)format;
  259. - (NSString *)descriptionWithCalendarFormat:(NSString *)format timeZone:(NSTimeZone *)timeZone;
  260. @end
  261.  
  262. @interface NSDate (NSCalendarDateExtras)
  263.  
  264. - initWithString:(NSString *)description;
  265.  
  266. - (NSCalendarDate *)dateWithCalendarFormat:(NSString *)format timeZone:(NSTimeZone *)aTimeZone;
  267.  
  268. - (NSString *)description;
  269.     /* these use an NSCalendarDate with the default time zone and format */
  270.  
  271. - (NSString *)descriptionWithCalendarFormat:(NSString *)format timeZone:(NSTimeZone *)aTimeZone;
  272.  
  273. @end
  274.  
  275.  
  276.